home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / wgdb-42.lha / wgdb-4.2 / gdb / gdb.info-2 < prev    next >
Text File  |  1992-09-11  |  48KB  |  1,176 lines
  1. Info file gdb.info, produced by Makeinfo, -*- Text -*- from input
  2. file gdb-all.texi.
  3.  
  4.    This file documents the GNU debugger GDB.
  5.  
  6.    Copyright (C) 1988, 1989, 1990, 1991 Free Software Foundation, Inc.
  7.  
  8.    Permission is granted to make and distribute verbatim copies of
  9. this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.  
  13.    Permission is granted to copy and distribute modified versions of
  14. this
  15. manual under the conditions for verbatim copying, provided also that
  16. the section entitled "GNU General Public License" is included
  17. exactly as in the original, and provided that the entire resulting
  18. derived work is distributed under the terms of a permission notice
  19. identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for
  23. modified versions, except that the section entitled "GNU General
  24. Public License" may be included in a translation approved by the
  25. Free Software Foundation instead of in the original English.
  26.  
  27. 
  28. File: gdb.info,  Node: Kill Process,  Prev: Attach,  Up: Running
  29.  
  30. Killing the Child Process
  31. =========================
  32.  
  33. `kill'
  34.      Kill the child process in which your program is running under GDB.
  35.  
  36.    This command is useful if you wish to debug a core dump instead of
  37. a
  38. running process.  GDB ignores any core dump file while your program
  39. is running.
  40.  
  41.    On some operating systems, a program can't be executed outside GDB
  42. while
  43. you have breakpoints set on it inside GDB.  You can use the `kill'
  44. command in this situation to permit running the program outside the
  45. debugger.
  46.  
  47.    The `kill' command is also useful if you wish to recompile and
  48. relink the program, since on many systems it is impossible to modify
  49. an executable file while it is running in a process.  In this case,
  50. when you next type `run', GDB will notice that the file has changed,
  51. and will re-read the symbol table (while trying to preserve your
  52. current breakpoint settings).
  53.  
  54. 
  55. File: gdb.info,  Node: Stopping,  Next: Stack,  Prev: Running,  Up: Top
  56.  
  57. Stopping and Continuing
  58. ***********************
  59.  
  60.    The principal purpose of using a debugger is so that you can stop
  61. your program before it terminates; or so that, if the program runs
  62. into trouble, you can investigate and find out why.
  63.  
  64.    Inside GDB, your program may stop for any of several reasons, such
  65. as a signal, a breakpoint, or reaching a new line after a GDB
  66. command such as `step'.  You may then examine and change variables,
  67. set
  68. new breakpoints or remove old ones, and then continue execution. 
  69. Usually, the messages shown by GDB provide ample explanation of the
  70. status of your program--but you can also explicitly request this
  71. information at any time.
  72.  
  73. `info program'
  74.      Display information about the status of your program: whether it
  75.      is running or not, what process it is, and why it stopped.
  76.  
  77. * Menu:
  78.  
  79. * Breakpoints::                 Breakpoints, Watchpoints, and Exceptions
  80. * Continuing and Stepping::     Resuming Execution
  81. * Signals::                     Signals
  82.  
  83. 
  84. File: gdb.info,  Node: Breakpoints,  Next: Continuing and Stepping,  Prev: Stopping,  Up: Stopping
  85.  
  86. Breakpoints, Watchpoints, and Exceptions
  87. ========================================
  88.  
  89.    A "breakpoint" makes your program stop whenever a certain point in
  90. the program is reached.  For each breakpoint, you can add various
  91. conditions to control in finer detail whether the program will stop.
  92. You can set breakpoints with the `break' command and its variants
  93. (*note Set Breaks::.), to specify the place where the program should
  94. stop by line number, function name or exact address in the program. 
  95. In languages with exception handling (such as GNU C++), you can also
  96. set breakpoints  where an exception is raised (*note Exception
  97. Handling::.).
  98.  
  99.    A "watchpoint" is a special breakpoint that stops your program
  100. when the value of an expression changes.  You must use a different
  101. command to set watchpoints (*note Set Watchpoints::.), but aside
  102. from that, you can manage a watchpoint like any other breakpoint:
  103. you enable, disable, and delete both breakpoints and watchpoints
  104. using the same commands.
  105.  
  106.    Each breakpoint or watchpoint is assigned a number when it is
  107. created; these numbers are successive integers starting with one. 
  108. In many of the commands for controlling various features of
  109. breakpoints you use the breakpoint number to say which breakpoint
  110. you want to change.  Each breakpoint may be "enabled" or "disabled";
  111. if
  112. disabled, it has no effect on the program until you enable it again.
  113.  
  114. * Menu:
  115.  
  116. * Set Breaks::                  Setting Breakpoints
  117. * Set Watchpoints::             Setting Watchpoints
  118. * Exception Handling::          Breakpoints and Exceptions
  119. * Delete Breaks::               Deleting Breakpoints
  120. * Disabling::                   Disabling Breakpoints
  121. * Conditions::                  Break Conditions
  122. * Break Commands::              Breakpoint Command Lists
  123. * Breakpoint Menus::            Breakpoint Menus
  124. * Error in Breakpoints::
  125.  
  126. 
  127. File: gdb.info,  Node: Set Breaks,  Next: Set Watchpoints,  Prev: Breakpoints,  Up: Breakpoints
  128.  
  129. Setting Breakpoints
  130. -------------------
  131.  
  132.    Breakpoints are set with the `break' command (abbreviated `b').
  133.  
  134.    You have several ways to say where the breakpoint should go.
  135.  
  136. `break FUNCTION'
  137.      Set a breakpoint at entry to function FUNCTION.  When using
  138.      source languages that permit overloading of symbols, such as
  139.      C++, FUNCTION may refer to more than one possible place to break.
  140.      *Note Breakpoint Menus::, for a discussion of that situation.
  141.  
  142. `break +OFFSET'
  143. `break -OFFSET'
  144.      Set a breakpoint some number of lines forward or back from the
  145.      position at which execution stopped in the currently selected
  146.      frame.
  147.  
  148. `break LINENUM'
  149.      Set a breakpoint at line LINENUM in the current source file. 
  150.      That file is the last file whose source text was printed.  This
  151.      breakpoint will stop the program just before it executes any of
  152.      the code on that line.
  153.  
  154. `break FILENAME:LINENUM'
  155.      Set a breakpoint at line LINENUM in source file FILENAME.
  156.  
  157. `break FILENAME:FUNCTION'
  158.      Set a breakpoint at entry to function FUNCTION found in file
  159.      FILENAME.  Specifying a file name as well as a function name is
  160.      superfluous except when multiple files contain similarly named
  161.      functions.
  162.  
  163. `break *ADDRESS'
  164.      Set a breakpoint at address ADDRESS.  You can use this to set
  165.      breakpoints in parts of the program which do not have debugging
  166.      information or source files.
  167.  
  168. `break'
  169.      When called without any arguments, `break' sets a breakpoint at
  170.      the next instruction to be executed in the selected stack frame
  171.      (*note Stack::.).  In any selected frame but the innermost,
  172.      this will cause the program to stop as soon as control returns
  173.     
  174.      to that frame.  This is similar to the effect of a `finish'
  175.      command in the frame inside the selected frame--except that
  176.      `finish' doesn't leave an active breakpoint.  If you use
  177.      `break' without an argument in the innermost frame, GDB will
  178.      stop the next time it reaches the current location; this may be
  179.      useful inside loops.
  180.  
  181.      GDB normally ignores breakpoints when it resumes execution,
  182.      until at least one instruction has been executed.  If it did
  183.      not do this, you would be unable to proceed past a breakpoint
  184.      without first disabling the breakpoint.  This rule applies
  185.      whether or not the breakpoint already existed when the program
  186.      stopped.
  187.  
  188. `break ... if COND'
  189.      Set a breakpoint with condition COND; evaluate the expression
  190.      COND each time the breakpoint is reached, and stop only if the
  191.      value is nonzero--that is, if COND evaluates as true.  `...'
  192.      stands for one of the possible arguments described above (or no
  193.      argument) specifying where to break.  *Note Conditions::, for
  194.      more information on breakpoint conditions.
  195.  
  196. `tbreak ARGS'
  197.      Set a breakpoint enabled only for one stop.  ARGS are the same
  198.      as for the `break' command, and the breakpoint is set in the
  199.      same way, but the breakpoint is automatically disabled the
  200.      first time it is hit.  *Note Disabling::.
  201.  
  202. `rbreak REGEX'
  203.      Set breakpoints on all functions matching the regular expression
  204.      REGEX.  This command sets an unconditional breakpoint on all
  205.      matches, printing a list of all breakpoints it set. Once these
  206.      breakpoints are set, they are treated just like the breakpoints
  207.      set with the `break' command.  They can be deleted, disabled,
  208.      made conditional, etc., in the standard ways.
  209.  
  210.      When debugging C++ programs, `rbreak' is useful for setting
  211.      breakpoints on overloaded functions that are not members of any
  212.      special classes.
  213.  
  214. `info breakpoints [N]'
  215. `info break [N]'
  216.      Print a list of all breakpoints (but not watchpoints) set and
  217.      not deleted, showing their numbers, where in the program they
  218.      are, and any special features in use for them. Disabled
  219.      breakpoints are included in the list, but marked as disabled.
  220.      `info break' with a breakpoint number N as argument lists only
  221.      that breakpoint.  The convenience variable `$_' and the default
  222.     
  223.      examining-address for the `x' command are set to the address of
  224.      the last breakpoint listed (*note Memory::.).  The equivalent
  225.      command for watchpoints is `info watch'.
  226.  
  227.    GDB allows you to set any number of breakpoints at the same place
  228. in the program.  There is nothing silly or meaningless about this. 
  229. When the breakpoints are conditional, this is even useful (*note
  230. Conditions::.).
  231.  
  232. 
  233. File: gdb.info,  Node: Set Watchpoints,  Next: Exception Handling,  Prev: Set Breaks,  Up: Breakpoints
  234.  
  235. Setting Watchpoints
  236. -------------------
  237.  
  238.    You can use a watchpoint to stop execution whenever the value of
  239. an expression changes, without having to predict a particular place
  240. where this may happen.
  241.  
  242.    Watchpoints currently execute two orders of magnitude more slowly
  243. than other breakpoints, but this can well be worth it to catch
  244. errors where you have no clue what part of your program is the
  245. culprit.  Some processors provide special hardware to support
  246. watchpoint evaluation; future releases of GDB will use such hardware
  247. if it is available.
  248.  
  249. `watch EXPR'
  250.      Set a watchpoint for an expression.
  251.  
  252. `info watchpoints'
  253.      This command prints a list of watchpoints; it is otherwise
  254.      similar to `info break'.
  255.  
  256. 
  257. File: gdb.info,  Node: Exception Handling,  Next: Delete Breaks,  Prev: Set Watchpoints,  Up: Breakpoints
  258.  
  259. Breakpoints and Exceptions
  260. --------------------------
  261.  
  262.    Some languages, such as GNU C++, implement exception handling. 
  263. You can use GDB to examine what caused the program to raise an
  264. exception, and to list the exceptions the program is prepared to
  265. handle at a given point in time.
  266.  
  267. `catch EXCEPTIONS'
  268.      You can set breakpoints at active exception handlers by using
  269.      the `catch' command.  EXCEPTIONS is a list of names of
  270.      exceptions to catch.
  271.  
  272.    You can use `info catch' to list active exception handlers; *note
  273. Frame Info::..
  274.  
  275.    There are currently some limitations to exception handling in GDB.
  276. These will be corrected in a future release.
  277.  
  278.    * If you call a function interactively, GDB normally returns
  279.      control to you when the function has finished executing.  If
  280.      the call raises an exception, however, the call may bypass the
  281.      mechanism that returns control to the user and cause the
  282.      program to simply continue running until it hits a breakpoint,
  283.      catches a signal that GDB is listening for, or exits.
  284.  
  285.    * You cannot raise an exception interactively.
  286.  
  287.    * You cannot interactively install an exception handler.
  288.  
  289.    Sometimes `catch' is not the best way to debug exception handling:
  290. if you need to know exactly where an exception is raised, it's
  291. better to stop *before* the exception handler is called, since that
  292. way you can see the stack before any unwinding takes place.  If you
  293. set a breakpoint in an exception handler instead, it may not be easy
  294. to find out where the exception was raised.
  295.  
  296.    To stop just before an exception handler is called, you need some
  297. knowledge of the implementation.  In the case of GNU C++, exceptions
  298. are raised by calling a library function named `__raise_exception'
  299. which has the following ANSI C interface:
  300.  
  301.          /* ADDR is where the exception identifier is stored.
  302.             ID is the exception identifier.  */
  303.          void __raise_exception (void **ADDR, void *ID);
  304.  
  305. To make the debugger catch all exceptions before any stack unwinding
  306. takes place, set a breakpoint on `__raise_exception' (*note
  307. Breakpoints::.).
  308.  
  309.    With a conditional breakpoint (*Note Conditions::) that depends on
  310. the value of ID, you can stop your program when a specific exception
  311. is raised.  You can use multiple conditional breakpoints to stop the
  312. program when any of a number of exceptions are raised.
  313.  
  314. 
  315. File: gdb.info,  Node: Delete Breaks,  Next: Disabling,  Prev: Exception Handling,  Up: Breakpoints
  316.  
  317. Deleting Breakpoints
  318. --------------------
  319.  
  320.    It is often necessary to eliminate a breakpoint or watchpoint once
  321. it has done its job and you no longer want the program to stop
  322. there.  This is called "deleting" the breakpoint.  A breakpoint that
  323. has been deleted no longer exists; it is forgotten.
  324.  
  325.    With the `clear' command you can delete breakpoints according to
  326. where they are in the program.  With the `delete' command you can
  327. delete individual breakpoints or watchpoints by specifying their
  328. breakpoint numbers.
  329.  
  330.    It is not necessary to delete a breakpoint to proceed past it. 
  331. GDB automatically ignores breakpoints on the first instruction to be
  332. executed when you continue execution without changing the execution
  333. address.
  334.  
  335. `clear'
  336.      Delete any breakpoints at the next instruction to be executed in
  337.      the selected stack frame (*note Selection::.).  When the
  338.      innermost frame is selected, this is a good way to delete a
  339.      breakpoint that the program just stopped at.
  340.  
  341. `clear FUNCTION'
  342. `clear FILENAME:FUNCTION'
  343.      Delete any breakpoints set at entry to the function FUNCTION.
  344.  
  345. `clear LINENUM'
  346. `clear FILENAME:LINENUM'
  347.      Delete any breakpoints set at or within the code of the
  348.      specified line.
  349.  
  350. `delete [breakpoints] [BNUMS...]'
  351.      Delete the breakpoints or watchpoints of the numbers specified
  352.      as arguments.  If no argument is specified, delete all
  353.      breakpoints (GDB asks confirmation, unless you've `set confirm
  354.      off').  You can abbreviate this command as `d'.
  355.  
  356. 
  357. File: gdb.info,  Node: Disabling,  Next: Conditions,  Prev: Delete Breaks,  Up: Breakpoints
  358.  
  359. Disabling Breakpoints
  360. ---------------------
  361.  
  362.    Rather than deleting a breakpoint or watchpoint, you might prefer
  363. to "disable" it.  This makes the breakpoint inoperative as if it had
  364. been deleted, but remembers the information on the breakpoint so
  365. that you can "enable" it again later.
  366.  
  367.    You disable and enable breakpoints and watchpoints with the
  368. `enable' and `disable' commands, optionally specifying one or more
  369. breakpoint numbers as arguments.  Use `info break' or `info watch'
  370. to print a list of breakpoints or watchpoints if you don't know
  371. which numbers to use.
  372.  
  373.    A breakpoint or watchpoint can have any of four different states
  374. of enablement:
  375.  
  376.    * Enabled.  The breakpoint will stop the program.  A breakpoint
  377.      set with the `break' command starts out in this state.
  378.  
  379.    * Disabled.  The breakpoint has no effect on the program.
  380.  
  381.    * Enabled once.  The breakpoint will stop the program, but when it
  382.      does so it will become disabled.  A breakpoint set with the
  383.      `tbreak' command starts out in this state.
  384.  
  385.    * Enabled for deletion.  The breakpoint will stop the program, but
  386.      immediately after it does so it will be deleted permanently.
  387.  
  388.    You can use the following commands to enable or disable
  389. breakpoints and watchpoints:
  390.  
  391. `disable [breakpoints] [BNUMS...]'
  392.      Disable the specified breakpoints--or all breakpoints, if none
  393.      are listed.  A disabled breakpoint has no effect but is not
  394.      forgotten.  All options such as ignore-counts, conditions and
  395.      commands are remembered in case the breakpoint is enabled again
  396.      later.  You may abbreviate `disable' as `dis'.
  397.  
  398. `enable [breakpoints] [BNUMS...]'
  399.      Enable the specified breakpoints (or all defined breakpoints). 
  400.      They become effective once again in stopping the program.
  401.  
  402. `enable [breakpoints] once BNUMS...'
  403.      Enable the specified breakpoints temporarily.  Each will be
  404.      disabled again the next time it stops the program.
  405.  
  406. `enable [breakpoints] delete BNUMS...'
  407.      Enable the specified breakpoints to work once and then die. 
  408.      Each of the breakpoints will be deleted the next time it stops
  409.      the program.
  410.  
  411.    Save for a breakpoint set with `tbreak' (*note Set Breaks::.),
  412. breakpoints that you set are initially enabled; subsequently, they
  413. become disabled or enabled only when you use one of the commands
  414. above.  (The command `until' can set and delete a breakpoint of its
  415. own,
  416. but it will not change the state of your other breakpoints; *note
  417. Continuing and Stepping::..)
  418.  
  419. 
  420. File: gdb.info,  Node: Conditions,  Next: Break Commands,  Prev: Disabling,  Up: Breakpoints
  421.  
  422. Break Conditions
  423. ----------------
  424.  
  425.    The simplest sort of breakpoint breaks every time the program
  426. reaches a specified place.  You can also specify a "condition" for a
  427. breakpoint.  A condition is just a Boolean expression in your
  428. programming language.  (*Note Expressions::).  A breakpoint with a
  429. condition evaluates the expression each time the program reaches it,
  430. and the program stops only if the condition is *true*.
  431.  
  432.    This is the converse of using assertions for program validation;
  433. in that situation, you want to stop when the assertion is
  434. violated--that is, when the condition is false.  In C, if you want
  435. to test an assertion expressed by the condition ASSERT, you should
  436. set the condition `! ASSERT' on the appropriate breakpoint.
  437.  
  438.    Conditions are also accepted for watchpoints; you may not need
  439. them, since a watchpoint is inspecting the value of an expression
  440. anyhow--but it might be simpler, say, to just set a watchpoint on a
  441. variable name, and specify a condition that tests whether the new
  442. value is an interesting one.
  443.  
  444.    Break conditions ca have side effects, and may even call functions
  445. in your program.  This can be useful, for example, to activate
  446. functions that log program progress, or to use your own print
  447. functions to format special data structures. The effects are
  448. completely
  449. predictable unless there is another enabled breakpoint at the same
  450. address.  (In that case, GDB might see the other breakpoint first
  451. and stop the program without checking the condition of this one.) 
  452. Note that breakpoint commands are usually more convenient and
  453. flexible for the purpose of performing side effects when a
  454. breakpoint is reached (*note Break Commands::.).
  455.  
  456.    Break conditions can be specified when a breakpoint is set, by
  457. using `if' in the arguments to the `break' command.  *Note Set
  458. Breaks::.  They can also be changed at any time with the `condition'
  459. command.  The `watch' command doesn't recognize the `if' keyword;
  460. `condition' is the only way to impose a further condition on a
  461. watchpoint.
  462.  
  463. `condition BNUM EXPRESSION'
  464.      Specify EXPRESSION as the break condition for breakpoint or
  465.      watchpoint number BNUM.  From now on, this breakpoint will stop
  466.      the program only if the value of EXPRESSION is true (nonzero,
  467.      in C).  When you use `condition', GDB checks EXPRESSION
  468.      immediately for syntactic correctness, and to determine whether
  469.      symbols in it have referents in the context of your breakpoint.
  470.      GDB does not actually evaluate EXPRESSION at the time the
  471.      `condition' command is given, however.  *Note Expressions::.
  472.  
  473. `condition BNUM'
  474.      Remove the condition from breakpoint number BNUM.  It becomes an
  475.      ordinary unconditional breakpoint.
  476.  
  477.    A special case of a breakpoint condition is to stop only when the
  478. breakpoint has been reached a certain number of times.  This is so
  479. useful that there is a special way to do it, using the "ignore
  480. count" of the breakpoint.  Every breakpoint has an ignore count,
  481. which is an integer.  Most of the time, the ignore count is zero,
  482. and therefore has no effect.  But if the program reaches a
  483. breakpoint whose ignore count is positive, then instead of stopping,
  484. it just decrements the ignore count by one and continues.  As a
  485. result,
  486. if the ignore count value is N, the breakpoint will not stop the
  487. next N times it is reached.
  488.  
  489. `ignore BNUM COUNT'
  490.      Set the ignore count of breakpoint number BNUM to COUNT.  The
  491.      next COUNT times the breakpoint is reached, your program's
  492.      execution will not stop; other than to decrement the ignore
  493.      count, GDB takes no action.
  494.  
  495.      To make the breakpoint stop the next time it is reached, specify
  496.      a count of zero.
  497.  
  498. `continue COUNT'
  499. `c COUNT'
  500. `fg COUNT'
  501.      Continue execution of the program, setting the ignore count of
  502.      the breakpoint that the program stopped at to COUNT minus one. 
  503.      Thus, the program will not stop at this breakpoint until the
  504.      COUNT'th time it is reached.
  505.  
  506.      An argument to this command is meaningful only when the program
  507.      stopped due to a breakpoint.  At other times, the argument to
  508.      `continue' is ignored.
  509.  
  510.      The synonym `fg' is provided purely for convenience, and has
  511.      exactly the same behavior as other forms of the command.
  512.  
  513.    If a breakpoint has a positive ignore count and a condition, the
  514. condition is not checked.  Once the ignore count reaches zero, the
  515. condition will be checked.
  516.  
  517.    You could achieve the effect of the ignore count with a condition
  518. such as `$foo-- <= 0' using a debugger convenience variable that is
  519. decremented each time.  *Note Convenience Vars::.
  520.  
  521. 
  522. File: gdb.info,  Node: Break Commands,  Next: Breakpoint Menus,  Prev: Conditions,  Up: Breakpoints
  523.  
  524. Breakpoint Command Lists
  525. ------------------------
  526.  
  527.    You can give any breakpoint (or watchpoint) a series of commands
  528. to execute when the program stops due to that breakpoint.  For
  529. example, you might want to print the values of certain expressions,
  530. or enable other breakpoints.
  531.  
  532. `commands [BNUM]'
  533. `... COMMAND-LIST ...'
  534. `end'
  535.      Specify a list of commands for breakpoint number BNUM.  The
  536.      commands themselves appear on the following lines.  Type a line
  537.      containing just `end' to terminate the commands.
  538.  
  539.      To remove all commands from a breakpoint, type `commands'
  540.      followed immediately by `end'; that is, give no commands.
  541.  
  542.      With no BNUM argument, `commands' refers to the last breakpoint
  543.      or watchpoint set (not to the breakpoint most recently
  544.      encountered).
  545.  
  546.    Pressing RET as a means of repeating the last GDB command is
  547. disabled within a COMMAND-LIST.
  548.  
  549.    You can use breakpoint commands to start the program up again. 
  550. Simply use the `continue' command, or `step', or any other command
  551. that resumes execution.  Subsequent commands in the command list are
  552. ignored.
  553.  
  554.    If the first command specified is `silent', the usual message
  555. about stopping at a breakpoint is not printed.  This may be
  556. desirable for breakpoints that are to print a specific message and
  557. then continue.  If the remaining commands too print nothing, you
  558. will see no sign that the breakpoint was reached at all.  `silent'
  559. is meaningful only at the beginning of a breakpoint command list.
  560.  
  561.    The commands `echo' and `output' that allow you to print precisely
  562. controlled output are often useful in silent breakpoints.  *Note
  563. Output::.
  564.  
  565.    For example, here is how you could use breakpoint commands to
  566. print the value of `x' at entry to `foo' whenever `x' is positive.
  567.  
  568.      break foo if x>0
  569.      commands
  570.      silent
  571.      echo x is\040
  572.      output x
  573.      echo \n
  574.      cont
  575.      end
  576.  
  577.    One application for breakpoint commands is to compensate for one
  578. bug so you can test for another.  Put a breakpoint just after the
  579. erroneous line of code, give it a condition to detect the case in
  580. which something erroneous has been done, and give it commands to
  581. assign correct values to any variables that need them.  End with the
  582. `continue' command so that the program does not stop, and start with
  583. the `silent' command so that no output is produced.  Here is an
  584. example:
  585.  
  586.      break 403
  587.      commands
  588.      silent
  589.      set x = y + 4
  590.      cont
  591.      end
  592.  
  593.    One deficiency in the operation of automatically continuing
  594. breakpoints under Unix appears when your program uses raw mode for
  595. the
  596. terminal.  GDB switches back to its own terminal modes (not raw)
  597. before executing commands, and then must switch back to raw mode
  598. when your program is continued.  This causes any pending terminal
  599. input to be lost.
  600.  
  601.    Under Unix, you can get around this problem by writing actions
  602. into the breakpoint condition rather than in commands.  For example
  603.  
  604.      condition 5  (x = y + 4), 0
  605.  
  606. specifies a condition expression (*Note Expressions::) that will
  607. change `x' as needed, then always have the value zero so the program
  608. will not stop.  No input is lost here, because GDB evaluates break
  609. conditions  without changing the terminal modes.  When you want to
  610. have nontrivial conditions for performing the side effects, the
  611. operators `&&', `||' and `?...:' may be useful.
  612.  
  613. 
  614. File: gdb.info,  Node: Breakpoint Menus,  Next: Error in Breakpoints,  Prev: Break Commands,  Up: Breakpoints
  615.  
  616. Breakpoint Menus
  617. ----------------
  618.  
  619.    Some programming languages (notably C++) permit a single function
  620. name to be defined several times, for application in different
  621. contexts.  This is called "overloading".  When a function name is
  622. overloaded, `break FUNCTION' is not enough to tell GDB where you
  623. want a breakpoint.  GDB offers you a menu of numbered choices for
  624. different possible breakpoints, and waits for your selection with
  625. the prompt `>'.  The first two options are always `[0] cancel' and
  626. `[1] all'.  Typing `1' sets a breakpoint at each definition of
  627. FUNCTION, and typing `0' aborts the `break' command without setting
  628. any new breakpoints.
  629.  
  630.    For example, the following session excerpt shows an attempt to set
  631. a breakpoint at the overloaded symbol `String::after'.  We choose
  632. three particular definitions of that function name:
  633.  
  634.      (gdb) b String::after
  635.      [0] cancel
  636.      [1] all
  637.      [2] file:String.cc; line number:867
  638.      [3] file:String.cc; line number:860
  639.      [4] file:String.cc; line number:875
  640.      [5] file:String.cc; line number:853
  641.      [6] file:String.cc; line number:846
  642.      [7] file:String.cc; line number:735
  643.      > 2 4 6
  644.      Breakpoint 1 at 0xb26c: file String.cc, line 867.
  645.      Breakpoint 2 at 0xb344: file String.cc, line 875.
  646.      Breakpoint 3 at 0xafcc: file String.cc, line 846.
  647.      Multiple breakpoints were set.
  648.      Use the "delete" command to delete unwanted breakpoints.
  649.      (gdb)
  650.  
  651. 
  652. File: gdb.info,  Node: Error in Breakpoints,  Prev: Breakpoint Menus,  Up: Breakpoints
  653.  
  654. "Cannot Insert Breakpoints"
  655. ---------------------------
  656.  
  657.    Under some operating systems, breakpoints cannot be used in a
  658. program if any other process is running that program.  In this
  659. situation, attempting to run or continue a program with a breakpoint
  660. causes GDB to stop the other process.
  661.  
  662.    When this happens, you have three ways to proceed:
  663.  
  664.   1. Remove or disable the breakpoints, then continue.
  665.  
  666.   2. Suspend GDB, and copy the file containing the program to a new
  667.      name.  Resume GDB and use the `exec-file' command to specify
  668.      that GDB should run the program under that name.  Then start
  669.      the program again.
  670.  
  671.   3. Relink the program so that the text segment is nonsharable,
  672.      using the linker option `-N'.  The operating system limitation
  673.      may not apply to nonsharable executables.
  674.  
  675. 
  676. File: gdb.info,  Node: Continuing and Stepping,  Next: Signals,  Prev: Breakpoints,  Up: Stopping
  677.  
  678. Continuing and Stepping
  679. =======================
  680.  
  681.    "Continuing" means resuming program execution until your program
  682. completes normally.  In contrast, "stepping" means executing just
  683. one more "step" of your program, where "step" may mean either one
  684. line of source code, or one machine instruction (depending on what
  685. particular command you use).  Either when continuing or when
  686. stepping, the program may stop even sooner, due to a breakpoint or
  687. to a signal.  (If due to a signal, you may want to use `handle', or
  688. use `signal 0' to resume execution; *note Signals::..)
  689.  
  690. `continue [IGNORE-COUNT]'
  691.      Resume program execution, at the address where the program last
  692.      stopped; any breakpoints set at that address are bypassed.  The
  693.      optional argument IGNORE-COUNT allows you to specify a further
  694.      number of times to ignore a breakpoint at this location; its
  695.      effect is like that of `ignore' (*note Conditions::.).
  696.  
  697.      To resume execution at a different place, you can use `return'
  698.      (*note Returning::.) to go back to the calling function; or
  699.      `jump' (*note Jumping::.) to go to an arbitrary location in
  700.      your program.
  701.  
  702.    A typical technique for using stepping is to set a breakpoint
  703. (*note Breakpoints::.) at the beginning of the function or the
  704. section of the program in which a problem is believed to lie, run
  705. the program until it stops at that breakpoint, and then step through
  706. the suspect area, examining the variables that are interesting,
  707. until you see the problem happen.
  708.  
  709. `step'
  710.      Continue running the program until control reaches a different
  711.      source line, then stop it and return control to GDB.  This
  712.      command is abbreviated `s'.
  713.  
  714.           *Warning:* If you use the `step' command while control is
  715.           within a function that was compiled without debugging
  716.           information, execution will proceed until control reaches
  717.           another function.
  718.  
  719. `step COUNT'
  720.      Continue running as in `step', but do so COUNT times.  If a
  721.      breakpoint is reached or a signal not related to stepping
  722.      occurs before COUNT steps, stepping stops right away.
  723.  
  724. `next [COUNT]'
  725.      Continue to the next source line in the current (innermost)
  726.      stack frame.  Similar to `step', but any function calls
  727.      appearing within the line of code are executed without
  728.      stopping.  Execution stops when control reaches a different
  729.      line of code at the stack level which was executing when the
  730.     
  731.      `next' command was given.  This command is abbreviated `n'.
  732.  
  733.      An argument COUNT is a repeat count, as for `step'.
  734.  
  735.      `next' within a function that lacks debugging information acts
  736.      like `step', but any function calls appearing within the code
  737.      of the function are executed without stopping.
  738.  
  739. `finish'
  740.      Continue running until just after function in the selected stack
  741.      frame returns.  Print the returned value (if any).
  742.  
  743.      Contrast this with the `return' command (*note Returning::.).
  744.  
  745. `until'
  746. `u'
  747.      Continue running until a source line past the current line, in
  748.      the current stack frame, is reached.  This command is used to
  749.      avoid single stepping through a loop more than once.  It is
  750.      like the `next' command, except that when `until' encounters a
  751.      jump, it automatically continues execution until the program
  752.      counter is greater than the address of the jump.
  753.  
  754.      This means that when you reach the end of a loop after single
  755.      stepping though it, `until' will cause the program to continue
  756.      execution until the loop is exited.  In contrast, a `next'
  757.      command at the end of a loop will simply step back to the
  758.      beginning of the loop, which would force you to step through
  759.      the next iteration.
  760.  
  761.      `until' always stops the program if it attempts to exit the
  762.      current stack frame.
  763.  
  764.      `until' may produce somewhat counterintuitive results if the
  765.      order of machine code does not match the order of the source
  766.      lines.  For example, in the following excerpt from a debugging
  767.      session, the `f' (`frame') command shows that execution is
  768.      stopped at line `206'; yet when we use `until', we get to line
  769.      `195':
  770.  
  771.           (gdb) f
  772.           #0  main (argc=4, argv=0xf7fffae8) at m4.c:206
  773.           206                 expand_input();
  774.           (gdb) until
  775.           195             for ( ; argc > 0; NEXTARG) {
  776.  
  777.      This happened because, for execution efficiency, the compiler
  778.      had generated code for the loop closure test at the end, rather
  779.     
  780.      than the start, of the loop--even though the test in a C
  781.      `for'-loop is written before the body of the loop.  The `until'
  782.      command appeared to step back to the beginning of the loop when
  783.      it advanced to this expression; however, it has not really gone
  784.      to an earlier statement--not in terms of the actual machine code.
  785.  
  786.      `until' with no argument works by means of single instruction
  787.      stepping, and hence is slower than `until' with an argument.
  788.  
  789. `until LOCATION'
  790. `u LOCATION'
  791.      Continue running the program until either the specified location
  792.      is reached, or the current stack frame returns.  LOCATION is
  793.      any of the forms of argument acceptable to `break' (*note Set
  794.      Breaks::.).  This form of the command uses breakpoints, and
  795.      hence is quicker than `until' without an argument.
  796.  
  797. `stepi'
  798. `si'
  799.      Execute one machine instruction, then stop and return to the
  800.      debugger.
  801.  
  802.      It is often useful to do `display/i $pc' when stepping by
  803.      machine instructions.  This will cause the next instruction to
  804.      be executed to be displayed automatically at each stop.  *Note
  805.      Auto Display::.
  806.  
  807.      An argument is a repeat count, as in `step'.
  808.  
  809. `nexti'
  810. `ni'
  811.      Execute one machine instruction, but if it is a function call,
  812.      proceed until the function returns.
  813.  
  814.      An argument is a repeat count, as in `next'.
  815.  
  816. 
  817. File: gdb.info,  Node: Signals,  Prev: Continuing and Stepping,  Up: Stopping
  818.  
  819. Signals
  820. =======
  821.  
  822.    A signal is an asynchronous event that can happen in a program. 
  823. The operating system defines the possible kinds of signals, and
  824. gives each kind a name and a number.  For example, in Unix `SIGINT'
  825. is the signal a program gets when you type an interrupt (often
  826. `C-c'); `SIGSEGV' is the signal a program gets from referencing a
  827. place in memory far away from all the areas in use; `SIGALRM' occurs
  828. when the alarm clock timer goes off (which happens only if the
  829. program has requested an alarm).
  830.  
  831.    Some signals, including `SIGALRM', are a normal part of the
  832. functioning of the program.  Others, such as `SIGSEGV', indicate
  833. errors; these signals are "fatal" (kill the program immediately) if
  834. the program has not specified in advance some other way to handle
  835. the signal.  `SIGINT' does not indicate an error in the program, but
  836. it is normally fatal so it can carry out the purpose of the
  837. interrupt: to kill the program.
  838.  
  839.    GDB has the ability to detect any occurrence of a signal in the
  840. program running under GDB's control.  You can tell GDB in advance
  841. what to do for each kind of signal.
  842.  
  843.    Normally, GDB is set up to ignore non-erroneous signals like
  844. `SIGALRM' (so as not to interfere with their role in the functioning
  845. of the program) but to stop the program immediately whenever an
  846. error signal happens.  You can change these settings with the
  847. `handle' command.
  848.  
  849. `info signals'
  850.      Print a table of all the kinds of signals and how GDB has been
  851.      told to handle each one.  You can use this to see the signal
  852.      numbers of all the defined types of signals.
  853.  
  854. `handle SIGNAL KEYWORDS...'
  855.      Change the way GDB handles signal SIGNAL.  SIGNAL can be the
  856.      number of a signal or its name (with or without the `SIG' at
  857.      the beginning).  The KEYWORDS say what change to make.
  858.  
  859.    The keywords allowed by the `handle' command can be abbreviated. 
  860. Their full names are:
  861.  
  862. `nostop'
  863.      GDB should not stop the program when this signal happens.  It
  864.      may still print a message telling you that the signal has come
  865.      in.
  866.  
  867. `stop'
  868.      GDB should stop the program when this signal happens.  This
  869.      implies the `print' keyword as well.
  870.  
  871. `print'
  872.      GDB should print a message when this signal happens.
  873.  
  874. `noprint'
  875.      GDB should not mention the occurrence of the signal at all. 
  876.      This implies the `nostop' keyword as well.
  877.  
  878. `pass'
  879.      GDB should allow the program to see this signal; the program
  880.      will be able to handle the signal, or may be terminated if the
  881.      signal is fatal and not handled.
  882.  
  883. `nopass'
  884.      GDB should not allow the program to see this signal.
  885.  
  886.    When a signal has been set to stop the program, the program cannot
  887. see the signal until you continue.  It will see the signal then, if
  888. `pass' is in effect for the signal in question at that time.  In
  889. other words, after GDB reports a signal, you can use the `handle'
  890. command with `pass' or `nopass' to control whether that signal will
  891. be seen by the program when you later continue it.
  892.  
  893.    You can also use the `signal' command to prevent the program from
  894. seeing a signal, or cause it to see a signal it normally would not
  895. see, or to give it any signal at any time.  For example, if the
  896. program stopped due to some sort of memory reference error, you
  897. might store correct values into the erroneous variables and
  898. continue, hoping to see more execution; but the program would
  899. probably terminate immediately as a result of the fatal signal once
  900. it sees the signal.  To prevent this, you can continue with `signal
  901. 0'.  *Note Signaling::.
  902.  
  903. 
  904. File: gdb.info,  Node: Stack,  Next: Source,  Prev: Stopping,  Up: Top
  905.  
  906. Examining the Stack
  907. *******************
  908.  
  909.    When your program has stopped, the first thing you need to know is
  910. where it stopped and how it got there.
  911.  
  912.    Each time your program performs a function call, the information
  913. about where in the program the call was made from is saved in a
  914. block of data called a "stack frame".  The frame also contains the
  915. arguments of the call and the local variables of the function that
  916. was called.  All the stack frames are allocated in a region of
  917. memory called the "call stack".
  918.  
  919.    When your program stops, the GDB commands for examining the stack
  920. allow you to see all of this information.
  921.  
  922.    One of the stack frames is "selected" by GDB and many GDB commands
  923. refer implicitly to the selected frame.  In particular, whenever you
  924. ask GDB for the value of a variable in the program, the value is
  925. found in the selected frame.  There are special GDB commands to
  926. select whichever frame you are interested in.
  927.  
  928.    When the program stops, GDB automatically selects the currently
  929. executing frame and describes it briefly as the `frame' command does
  930. (*note Frame Info::.).
  931.  
  932. * Menu:
  933.  
  934. * Frames::                      Stack Frames
  935. * Backtrace::                   Backtraces
  936. * Selection::                   Selecting a Frame
  937. * Frame Info::                  Information on a Frame
  938.  
  939. 
  940. File: gdb.info,  Node: Frames,  Next: Backtrace,  Prev: Stack,  Up: Stack
  941.  
  942. Stack Frames
  943. ============
  944.  
  945.    The call stack is divided up into contiguous pieces called "stack
  946. frames", or "frames" for short; each frame is the data associated
  947. with one call to one function.  The frame contains the arguments
  948. given to the function, the function's local variables, and the
  949. address at which the function is executing.
  950.  
  951.    When your program is started, the stack has only one frame, that
  952. of the function `main'.  This is called the "initial" frame or the
  953. "outermost" frame.  Each time a function is called, a new frame is
  954. made.  Each time a function returns, the frame for that function
  955. invocation is eliminated.  If a function is recursive, there can be
  956. many frames for the same function.  The frame for the function in
  957. which execution is actually occurring is called the "innermost"
  958. frame.  This is the most recently created of all the stack frames
  959. that still exist.
  960.  
  961.    Inside your program, stack frames are identified by their
  962. addresses.  A stack frame consists of many bytes, each of which has
  963. its own address; each kind of computer has a convention for choosing
  964. one of those bytes whose address serves as the address of the frame.
  965. Usually this address is kept in a register called the "frame pointer
  966. register" while execution is going on in that frame.
  967.  
  968.    GDB assigns numbers to all existing stack frames, starting with
  969. zero for the innermost frame, one for the frame that called it, and
  970. so on upward.  These numbers do not really exist in your program;
  971. they are assigned by GDB to give you a way of designating stack
  972. frames in GDB commands.
  973.  
  974.    Some compilers allow functions to be compiled so that they operate
  975. without stack frames.  (For example, the `gcc' option
  976. `-fomit-frame-pointer' will generate functions without a frame.)
  977. This is occasionally done with heavily used library functions to
  978. save the frame setup time.  GDB has limited facilities for dealing
  979. with these function invocations.  If the innermost function
  980. invocation has no stack frame, GDB will nevertheless regard it as
  981. though it had a separate frame, which is numbered zero as usual,
  982. allowing correct tracing of the function call chain.  However, GDB
  983. has no provision for frameless functions elsewhere in the stack.
  984.  
  985. 
  986. File: gdb.info,  Node: Backtrace,  Next: Selection,  Prev: Frames,  Up: Stack
  987.  
  988. Backtraces
  989. ==========
  990.  
  991.    A backtrace is a summary of how the program got where it is.  It
  992. shows one line per frame, for many frames, starting with the
  993. currently executing frame (frame zero), followed by its caller
  994. (frame one), and on up the stack.
  995.  
  996. `backtrace'
  997. `bt'
  998.      Print a backtrace of the entire stack: one line per frame for
  999.      all frames in the stack.
  1000.  
  1001.      You can stop the backtrace at any time by typing the system
  1002.      interrupt character, normally `C-c'.
  1003.  
  1004. `backtrace N'
  1005. `bt N'
  1006.      Similar, but print only the innermost N frames.
  1007.  
  1008. `backtrace -N'
  1009. `bt -N'
  1010.      Similar, but print only the outermost N frames.
  1011.  
  1012.    The names `where' and `info stack' (abbreviated `info s') are
  1013. additional aliases for `backtrace'.
  1014.  
  1015.    Each line in the backtrace shows the frame number and the function
  1016. name.  The program counter value is also shown--unless you use `set
  1017. print address off'.  The backtrace also shows the source file name
  1018. and line number, as well as the arguments to the function.  The
  1019. program counter value is omitted if it is at the beginning of the
  1020. code for that line number.
  1021.  
  1022.    Here is an example of a backtrace.  It was made with the command
  1023. `bt 3', so it shows the innermost three frames.
  1024.  
  1025.      #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) at builtin.c:993
  1026.      #1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
  1027.      #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
  1028.          at macro.c:71
  1029.      (More stack frames follow...)
  1030.  
  1031. The display for frame zero doesn't begin with a program counter
  1032. value, indicating that the program has stopped at the beginning of
  1033. the code for line `993' of `builtin.c'.
  1034.  
  1035. 
  1036. File: gdb.info,  Node: Selection,  Next: Frame Info,  Prev: Backtrace,  Up: Stack
  1037.  
  1038. Selecting a Frame
  1039. =================
  1040.  
  1041.    Most commands for examining the stack and other data in the
  1042. program work on whichever stack frame is selected at the moment. 
  1043. Here are the commands for selecting a stack frame; all of them
  1044. finish by printing a brief description of the stack frame just
  1045. selected.
  1046.  
  1047. `frame N'
  1048. `f N'
  1049.      Select frame number N.  Recall that frame zero is the innermost
  1050.      (currently executing) frame, frame one is the frame that called
  1051.      the innermost one, and so on.  The highest-numbered frame is
  1052.      `main''s frame.
  1053.  
  1054. `frame ADDR'
  1055. `f ADDR'
  1056.      Select the frame at address ADDR.  This is useful mainly if the
  1057.      chaining of stack frames has been damaged by a bug, making it
  1058.      impossible for GDB to assign numbers properly to all frames. 
  1059.      In addition, this can be useful when the program has multiple
  1060.      stacks and switches between them.
  1061.  
  1062.      On the SPARC architecture, `frame' needs two addresses to select
  1063.      an arbitrary frame: a frame pointer and a stack pointer.
  1064.  
  1065. `up N'
  1066.      Move N frames up the stack.  For positive numbers N, this
  1067.      advances toward the outermost frame, to higher frame numbers,
  1068.      to frames that have existed longer.  N defaults to one.
  1069.  
  1070. `down N'
  1071.      Move N frames down the stack.  For positive numbers N, this
  1072.      advances toward the innermost frame, to lower frame numbers, to
  1073.      frames that were created more recently.  N defaults to one. 
  1074.      You may abbreviate `down' as `do'.
  1075.  
  1076.    All of these commands end by printing two lines of output
  1077. describing the frame.  The first line shows the frame number, the
  1078. function name, the arguments, and the source file and line number of
  1079. execution in that frame.  The second line shows the text of that
  1080. source line.  For example:
  1081.  
  1082.      (gdb) up
  1083.      #1  0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) at env.c:10
  1084.      10              read_input_file (argv[i]);
  1085.  
  1086.    After such a printout, the `list' command with no arguments will
  1087. print ten lines centered on the point of execution in the frame. 
  1088. *Note List::.
  1089.  
  1090. `up-silently N'
  1091. `down-silently N'
  1092.      These two commands are variants of `up' and `down',
  1093.      respectively; they differ in that they do their work silently,
  1094.      without causing display of the new frame.  They are intended
  1095.      primarily for use in GDB command scripts, where the output
  1096.      might be unnecessary and distracting.
  1097.  
  1098. 
  1099. File: gdb.info,  Node: Frame Info,  Prev: Selection,  Up: Stack
  1100.  
  1101. Information About a Frame
  1102. =========================
  1103.  
  1104.    There are several other commands to print information about the
  1105. selected stack frame.
  1106.  
  1107. `frame'
  1108. `f'
  1109.      When used without any argument, this command does not change
  1110.      which frame is selected, but prints a brief description of the
  1111.      currently selected stack frame.  It can be abbreviated `f'. 
  1112.      With an argument, this command is used to select a stack frame
  1113.      (*note Selection::.).
  1114.  
  1115. `info frame'
  1116. `info f'
  1117.      This command prints a verbose description of the selected stack
  1118.      frame, including the address of the frame, the addresses of the
  1119.      next frame down (called by this frame) and the next frame up
  1120.      (caller of this frame), the language that the source code
  1121.      corresponding to this frame was written in, the address of the
  1122.      frame's arguments, the program counter saved in it (the address
  1123.      of execution in the caller frame), and which registers were
  1124.      saved in the frame.  The verbose description is useful when
  1125.      something has gone wrong that has made the stack format fail to
  1126.      fit the usual conventions.
  1127.  
  1128. `info frame ADDR'
  1129. `info f ADDR'
  1130.      Print a verbose description of the frame at address ADDR,
  1131.      without selecting that frame.  The selected frame remains
  1132.      unchanged by this command.
  1133.  
  1134. `info args'
  1135.      Print the arguments of the selected frame, each on a separate
  1136.      line.
  1137.  
  1138. `info locals'
  1139.      Print the local variables of the selected frame, each on a
  1140.      separate line.  These are all variables declared static or
  1141.      automatic within all program blocks that execution in this
  1142.      frame
  1143.      is currently inside of.
  1144.  
  1145. `info catch'
  1146.      Print a list of all the exception handlers that are active in
  1147.      the current stack frame at the current point of execution.  To
  1148.      see other exception handlers, visit the associated frame (using
  1149.      the `up', `down', or `frame' commands); then type `info catch'.
  1150.      *Note Exception Handling::.
  1151.  
  1152. 
  1153. File: gdb.info,  Node: Source,  Next: Data,  Prev: Stack,  Up: Top
  1154.  
  1155. Examining Source Files
  1156. **********************
  1157.  
  1158.    GDB can print parts of your program's source, since the debugging
  1159. information recorded in your program tells GDB what source files
  1160. were used to built it.  When your program stops, GDB spontaneously
  1161. prints the line where it stopped.  Likewise, when you select a stack
  1162. frame (*note Selection::.), GDB prints the line where execution in
  1163. that frame has stopped.  You can print other portions of source
  1164. files by explicit command.
  1165.  
  1166.    If you use GDB through its GNU Emacs interface, you may prefer to
  1167. use Emacs facilities to view source; *note Emacs::..
  1168.  
  1169. * Menu:
  1170.  
  1171. * List::                        Printing Source Lines
  1172. * Search::                      Searching Source Files
  1173. * Source Path::                 Specifying Source Directories
  1174. * Machine Code::                Source and Machine Code
  1175.  
  1176.